/*
 * Copyright 2002-2017 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.core.type;

import org.springframework.lang.Nullable;

/**
 * Interface that defines abstract metadata of a specific class,
 * in a form that does not require that class to be loaded yet.
 *
 * @author Juergen Hoeller
 * @since 2.5
 * @see StandardClassMetadata
 * @see org.springframework.core.type.classreading.MetadataReader#getClassMetadata()
 * @see AnnotationMetadata
 */

/**
 ClassMetadata 接口定义了特定类的抽象元数据，无需加载该类：

 1. ClassMetadata 接口内部成员详解
	 String getClassName(): 返回底层类的名称
	 boolean isInterface(): 返回底层类是否表示一个接口
	 boolean isAnnotation(): 返回底层类是否表示一个注解类型
	 boolean isAbstract(): 返回底层类是否标记为抽象
	 boolean isConcrete(): 返回底层类是否为具体类（既不是接口也不是抽象类）
	 boolean isFinal(): 返回底层类是否标记为'final'
	 boolean isIndependent(): 确定底层类是否独立（顶级类或可以独立构造的嵌套类）
	 boolean hasEnclosingClass(): 返回底层类是否在封闭类中声明
	 String getEnclosingClassName(): 返回底层类的封闭类名称，如果是顶级类则返回null
	 boolean hasSuperClass(): 返回底层类是否有父类
	 String getSuperClassName(): 返回底层类的父类名称，如果没有定义父类则返回null
	 String[] getInterfaceNames(): 返回底层类实现的所有接口名称
	 String[] getMemberClassNames(): 返回该类声明的所有成员类名称
 2. 继承树和实现类
 	ClassMetadata 是一个接口，其继承和实现关系如下：
 实现类：
	 StandardClassMetadata：基于JVM反射的标准实现
	 org.springframework.core.type.classreading.ClassMetadataReadingVisitor：基于ASM字节码读取的实现
	 AnnotationMetadata：继承自 ClassMetadata，扩展了注解相关功能
 3. 与其他类和接口的关系
	 与 StandardClassMetadata：实现关系，是其标准实现
	 与 AnnotationMetadata：继承关系，AnnotationMetadata 扩展了 ClassMetadata 并添加了注解相关功能
	 与 MetadataReader：通过 MetadataReader.getClassMetadata() 方法获取 ClassMetadata 实例
	 与 ClassMetadataReadingVisitor：同样是 ClassMetadata 的实现，基于ASM字节码分析
 4. 总结
 	ClassMetadata 是Spring框架中用于在不加载类的情况下读取类的基本结构信息的核心接口。它提供了访问类的基本属性（如类名、接口、父类、是否为接口等）的方法，使得Spring能够在类路径扫描和组件注册时高效地处理类结构信息，而无需实际加载类到JVM中。这个接口是 AnnotationMetadata 的基础，后者在其基础上增加了注解处理功能。
 5. 应用场景
	 组件扫描：Spring在扫描类路径下的组件时，首先使用 ClassMetadata 来判断类的基本结构
	 类过滤：根据类的属性（如是否为接口、是否为抽象类等）进行过滤
	 依赖分析：分析类的继承关系和实现的接口
	 条件化配置：配合 @Conditional 注解，基于类结构信息判断是否应该加载某个配置
	 AOP代理决策：根据类的结构信息决定代理策略
	 类路径扫描优化：在不需要加载类的情况下快速获取类的基本信息
	 框架内部处理：Spring框架内部大量使用此类来处理类元数据信息
	 这些应用场景都利用了 ClassMetadata 在不加载类的情况下读取类结构信息的能力，提高了框架的性能和灵活性。
 */
public interface ClassMetadata {

	/**
	 * Return the name of the underlying class.
	 */
	String getClassName();

	/**
	 * Return whether the underlying class represents an interface.
	 */
	boolean isInterface();

	/**
	 * Return whether the underlying class represents an annotation.
	 * @since 4.1
	 */
	boolean isAnnotation();

	/**
	 * Return whether the underlying class is marked as abstract.
	 */
	boolean isAbstract();

	/**
	 * Return whether the underlying class represents a concrete class,
	 * i.e. neither an interface nor an abstract class.
	 */
	default boolean isConcrete() {
		return !(isInterface() || isAbstract());
	}

	/**
	 * Return whether the underlying class is marked as 'final'.
	 */
	boolean isFinal();

	/**
	 * Determine whether the underlying class is independent, i.e. whether
	 * it is a top-level class or a nested class (static inner class) that
	 * can be constructed independently from an enclosing class.
	 *
	 * 到底是顶级类还是嵌套类(静态内部类)，可以独立于外部类构造
	 */
	boolean isIndependent();

	/**
	 * Return whether the underlying class is declared within an enclosing
	 * class (i.e. the underlying class is an inner/nested class or a
	 * local class within a method).
	 * <p>If this method returns {@code false}, then the underlying
	 * class is a top-level class.
	 */
	default boolean hasEnclosingClass() {
		return (getEnclosingClassName() != null);
	}

	/**
	 * Return the name of the enclosing class of the underlying class,
	 * or {@code null} if the underlying class is a top-level class.
	 */
	@Nullable
	String getEnclosingClassName();

	/**
	 * Return whether the underlying class has a super class.
	 */
	default boolean hasSuperClass() {
		return (getSuperClassName() != null);
	}

	/**
	 * Return the name of the super class of the underlying class,
	 * or {@code null} if there is no super class defined.
	 */
	@Nullable
	String getSuperClassName();

	/**
	 * Return the names of all interfaces that the underlying class
	 * implements, or an empty array if there are none.
	 */
	String[] getInterfaceNames();

	/**
	 * Return the names of all classes declared as members of the class represented by
	 * this ClassMetadata object. This includes public, protected, default (package)
	 * access, and private classes and interfaces declared by the class, but excludes
	 * inherited classes and interfaces. An empty array is returned if no member classes
	 * or interfaces exist.
	 * @since 3.1
	 */
	String[] getMemberClassNames();

}
